home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  16.1 KB  |  531 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces
  5.  
  6.      Version:    Technology:    MacOS
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1993-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __NAMEREGISTRY__
  18. #define __NAMEREGISTRY__
  19.  
  20. #ifndef __MACTYPES__
  21.     #include <MacTypes.h>
  22. #endif
  23.  
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=power
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47. /*******************************************************************************
  48.  * 
  49.  * Foundation Types
  50.  *
  51.  */
  52. /* Value of a property */
  53. typedef void *                            RegPropertyValue;
  54. /* Length of property value */
  55. typedef UInt32                             RegPropertyValueSize;
  56. /*******************************************************************************
  57.  * 
  58.  * RegEntryID    :    The Global x-Namespace Entry Identifier
  59.  *
  60.  */
  61.  
  62. struct RegEntryID {
  63.     UInt32                             contents[4];
  64. };
  65. typedef struct RegEntryID                RegEntryID;
  66. typedef RegEntryID *                    RegEntryIDPtr;
  67. /*******************************************************************************
  68.  *
  69.  * Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  70.  *
  71.  *    o Names are a colon-separated list of name components.  Name components
  72.  *      may not themselves contain colons.  
  73.  *    o Names are presented as null-terminated ASCII character strings.
  74.  *    o Names follow similar parsing rules to Apple file system absolute
  75.  *      and relative paths.  However the '::' parent directory syntax is
  76.  *      not currently supported.
  77.  */
  78. /* Max length of Entry Name */
  79. enum {
  80.     kRegCStrMaxEntryNameLength    = 47
  81. };
  82.  
  83. /* Entry Names are single byte ASCII */
  84.  
  85. typedef char                             RegCStrEntryName;
  86. typedef char *                            RegCStrEntryNamePtr;
  87. /* length of RegCStrEntryNameBuf =  kRegCStrMaxEntryNameLength+1*/
  88. typedef char                             RegCStrEntryNameBuf[48];
  89. typedef char                             RegCStrPathName;
  90. typedef UInt32                             RegPathNameSize;
  91. enum {
  92.     kRegPathNameSeparator        = ':',                            /* 0x3A */
  93.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  94.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  95. };
  96.  
  97. /*******************************************************************************
  98.  *
  99.  * Property Name and ID Definitions
  100.  *    (Applies to all Properties Regardless of NameSpace)
  101.  */
  102. enum {
  103.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  104.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  105. };
  106.  
  107. typedef char                             RegPropertyNameBuf[32];
  108. typedef char                             RegPropertyName;
  109. typedef char *                            RegPropertyNamePtr;
  110. /*******************************************************************************
  111.  *
  112.  * Iteration Operations
  113.  *
  114.  *    These specify direction when traversing the name relationships
  115.  */
  116. typedef UInt32                             RegIterationOp;
  117. typedef RegIterationOp                     RegEntryIterationOp;
  118. enum {
  119.                                                                 /* Absolute locations*/
  120.     kRegIterRoot                = 0x00000002,                    /* "Upward" Relationships    */
  121.     kRegIterParents                = 0x00000003,                    /* include all  parent(s) of entry */
  122.                                                                 /* "Downward" Relationships*/
  123.     kRegIterChildren            = 0x00000004,                    /* include all children */
  124.     kRegIterSubTrees            = 0x00000005,                    /* include all sub trees of entry */
  125.     kRegIterDescendants            = 0x00000005,                    /* include all descendants of entry */
  126.                                                                 /* "Horizontal" Relationships    */
  127.     kRegIterSibling                = 0x00000006,                    /* include all siblings */
  128.                                                                 /* Keep doing the same thing*/
  129.     kRegIterContinue            = 0x00000001
  130. };
  131.  
  132. /*******************************************************************************
  133.  *
  134.  * Name Entry and Property Modifiers
  135.  *
  136.  *
  137.  *
  138.  * Modifiers describe special characteristics of names
  139.  * and properties.  Modifiers might be supported for
  140.  * some names and not others.
  141.  * 
  142.  * Device Drivers should not rely on functionality
  143.  * specified as a modifier.
  144.  */
  145. typedef UInt32                             RegModifiers;
  146. typedef RegModifiers                     RegEntryModifiers;
  147. typedef RegModifiers                     RegPropertyModifiers;
  148. enum {
  149.     kRegNoModifiers                = 0x00000000,                    /* no entry modifiers in place */
  150.     kRegUniversalModifierMask    = 0x0000FFFF,                    /* mods to all entries */
  151.     kRegNameSpaceModifierMask    = 0x00FF0000,                    /* mods to all entries within namespace */
  152.     kRegModifierMask            = (long)0xFF000000                /* mods to just this entry */
  153. };
  154.  
  155. /* Universal Property Modifiers */
  156. enum {
  157.     kRegPropertyValueIsSavedToNVRAM = 0x00000020,                /* property is non-volatile (saved in NVRAM) */
  158.     kRegPropertyValueIsSavedToDisk = 0x00000040                    /* property is non-volatile (saved on disk) */
  159. };
  160.  
  161. /* NameRegistry version, Gestalt/PEF-style -- MUST BE KEPT IN SYNC WITH MAKEFILE !! */
  162. enum {
  163.     LatestNR_PEFVersion            = 0x01030000                    /* latest NameRegistryLib version (Gestalt/PEF-style) */
  164. };
  165.  
  166. /* ///////////////////////
  167. //
  168. // The Registry API
  169. //
  170. /////////////////////// */
  171. /* NameRegistry dispatch indexes */
  172. enum {
  173.     kSelectRegistryEntryIDInit    = 0,
  174.     kSelectRegistryEntryIDCompare = 1,
  175.     kSelectRegistryEntryIDCopy    = 2,
  176.     kSelectRegistryEntryIDDispose = 3,
  177.     kSelectRegistryCStrEntryCreate = 4,
  178.     kSelectRegistryEntryDelete    = 5,
  179.     kSelectRegistryEntryCopy    = 6,
  180.     kSelectRegistryEntryIterateCreate = 7,
  181.     kSelectRegistryEntryIterateDispose = 8,
  182.     kSelectRegistryEntryIterateSet = 9,
  183.     kSelectRegistryEntryIterate    = 10,
  184.     kSelectRegistryEntrySearch    = 11,
  185.     kSelectRegistryCStrEntryLookup = 12,
  186.     kSelectRegistryEntryToPathSize = 13,
  187.     kSelectRegistryCStrEntryToPath = 14,
  188.     kSelectRegistryCStrEntryToName = 15,
  189.     kSelectRegistryPropertyCreate = 16,
  190.     kSelectRegistryPropertyDelete = 17,
  191.     kSelectRegistryPropertyRename = 18,
  192.     kSelectRegistryPropertyIterateCreate = 19,
  193.     kSelectRegistryPropertyIterateDispose = 20,
  194.     kSelectRegistryPropertyIterate = 21,
  195.     kSelectRegistryPropertyGetSize = 22,
  196.     kSelectRegistryPropertyGet    = 23,
  197.     kSelectRegistryPropertySet    = 24,
  198.     kSelectRegistryEntryGetMod    = 25,
  199.     kSelectRegistryEntrySetMod    = 26,
  200.     kSelectRegistryPropertyGetMod = 27,
  201.     kSelectRegistryPropertySetMod = 28,
  202.     kSelectRegistryEntryMod        = 29,
  203.     kSelectRegistryEntryPropertyMod = 30,                        /* if you add more selectors here, remember to change 'kSelectRegistryHighestSelector' below*/
  204.     kSelectRegistryHighestSelector = kSelectRegistryEntryPropertyMod
  205. };
  206.  
  207.  
  208. /* ///////////////////////
  209. //
  210. // Entry Management
  211. //
  212. /////////////////////// */
  213.  
  214. /*-------------------------------
  215.  * EntryID handling
  216.  */
  217. /*
  218.  * Initialize an EntryID to a known invalid state
  219.  *   note: invalid != uninitialized
  220.  */
  221. EXTERN_API_C( OSStatus )
  222. RegistryEntryIDInit                (RegEntryID *            id)                                    TWOWORDINLINE(0x7000, 0xABE9);
  223.  
  224. /*
  225.  * Compare EntryID's for equality or if invalid
  226.  *
  227.  * If a NULL value is given for either id1 or id2, the other id 
  228.  * is compared with an invalid ID.  If both are NULL, the id's 
  229.  * are consided equal (result = true). 
  230.  */
  231. EXTERN_API_C( Boolean )
  232. RegistryEntryIDCompare            (const RegEntryID *        id1,
  233.                                  const RegEntryID *        id2)                                TWOWORDINLINE(0x7001, 0xABE9);
  234.  
  235. /*
  236.  * Copy an EntryID
  237.  */
  238. EXTERN_API_C( OSStatus )
  239. RegistryEntryIDCopy                (const RegEntryID *        src,
  240.                                  RegEntryID *            dst)                                TWOWORDINLINE(0x7002, 0xABE9);
  241.  
  242. /*
  243.  * Free an ID so it can be reused.
  244.  */
  245. EXTERN_API_C( OSStatus )
  246. RegistryEntryIDDispose            (RegEntryID *            id)                                    TWOWORDINLINE(0x7003, 0xABE9);
  247.  
  248. /*-------------------------------
  249.  * Adding and removing entries
  250.  *
  251.  * If (parentEntry) is NULL, the name is assumed
  252.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  253.  */
  254. EXTERN_API_C( OSStatus )
  255. RegistryCStrEntryCreate            (const RegEntryID *        parentEntry,
  256.                                  const RegCStrPathName * name,
  257.                                  RegEntryID *            newEntry)                            TWOWORDINLINE(0x7004, 0xABE9);
  258.  
  259. EXTERN_API_C( OSStatus )
  260. RegistryEntryDelete                (const RegEntryID *        id)                                    TWOWORDINLINE(0x7005, 0xABE9);
  261.  
  262. EXTERN_API_C( OSStatus )
  263. RegistryEntryCopy                (RegEntryID *            parentEntryID,
  264.                                  RegEntryID *            sourceDevice,
  265.                                  RegEntryID *            destDevice)                            TWOWORDINLINE(0x7006, 0xABE9);
  266.  
  267. /*---------------------------
  268.  * Traversing the namespace
  269.  *
  270.  * To support arbitrary namespace implementations in the future,
  271.  * I have hidden the form that the place pointer takes.  The previous
  272.  * interface exposed the place pointer by specifying it as a
  273.  * RegEntryID.
  274.  *
  275.  * I have also removed any notion of returning the entries
  276.  * in a particular order, because an implementation might
  277.  * return the names in semi-random order.  Many name service
  278.  * implementations will store the names in a hashed lookup
  279.  * table.
  280.  *
  281.  * Writing code to traverse some set of names consists of
  282.  * a call to begin the iteration, the iteration loop, and
  283.  * a call to end the iteration.  The begin call initializes
  284.  * the iteration cookie data structure.  The call to end the 
  285.  * iteration should be called even in the case of error so 
  286.  * that allocated data structures can be freed.
  287.  *
  288.  *    Create(...)
  289.  *    do {
  290.  *        Iterate(...);
  291.  *    } while (!done);
  292.  *    Dispose(...);
  293.  *
  294.  * This is the basic code structure for callers of the iteration
  295.  * interface.
  296.  */
  297. typedef struct OpaqueRegEntryIter*         RegEntryIter;
  298. /* 
  299.  * create/dispose the iterator structure
  300.  *   defaults to root with relationship = kRegIterDescendants
  301.  */
  302. EXTERN_API_C( OSStatus )
  303. RegistryEntryIterateCreate        (RegEntryIter *            cookie)                                TWOWORDINLINE(0x7007, 0xABE9);
  304.  
  305. EXTERN_API_C( OSStatus )
  306. RegistryEntryIterateDispose        (RegEntryIter *            cookie)                                TWOWORDINLINE(0x7008, 0xABE9);
  307.  
  308. /* 
  309.  * set Entry Iterator to specified entry
  310.  */
  311. EXTERN_API_C( OSStatus )
  312. RegistryEntryIterateSet            (RegEntryIter *            cookie,
  313.                                  const RegEntryID *        startEntryID)                        TWOWORDINLINE(0x7009, 0xABE9);
  314.  
  315. /*
  316.  * Return each value of the iteration
  317.  *
  318.  * return entries related to the current entry
  319.  * with the specified relationship
  320.  */
  321. EXTERN_API_C( OSStatus )
  322. RegistryEntryIterate            (RegEntryIter *            cookie,
  323.                                  RegEntryIterationOp     relationship,
  324.                                  RegEntryID *            foundEntry,
  325.                                  Boolean *                done)                                TWOWORDINLINE(0x700A, 0xABE9);
  326.  
  327. /*
  328.  * return entries with the specified property
  329.  *
  330.  * A NULL RegPropertyValue pointer will return an
  331.  * entry with the property containing any value.
  332.  */
  333. EXTERN_API_C( OSStatus )
  334. RegistryEntrySearch                (RegEntryIter *            cookie,
  335.                                  RegEntryIterationOp     relationship,
  336.                                  RegEntryID *            foundEntry,
  337.                                  Boolean *                done,
  338.                                  const RegPropertyName * propertyName,
  339.                                  const void *            propertyValue,
  340.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x700B, 0xABE9);
  341.  
  342. /*--------------------------------
  343.  * Find a name in the namespace
  344.  *
  345.  * This is the fast lookup mechanism.
  346.  * NOTE:  A reverse lookup mechanism
  347.  *      has not been provided because
  348.  *        some name services may not
  349.  *        provide a fast, general reverse
  350.  *        lookup.
  351.  */
  352. EXTERN_API_C( OSStatus )
  353. RegistryCStrEntryLookup            (const RegEntryID *        searchPointID,
  354.                                  const RegCStrPathName * pathName,
  355.                                  RegEntryID *            foundEntry)                            TWOWORDINLINE(0x700C, 0xABE9);
  356.  
  357. /*---------------------------------------------
  358.  * Convert an entry to a rooted name string
  359.  *
  360.  * A utility routine to turn an Entry ID
  361.  * back into a name string.
  362.  */
  363. EXTERN_API_C( OSStatus )
  364. RegistryEntryToPathSize            (const RegEntryID *        entryID,
  365.                                  RegPathNameSize *        pathSize)                            TWOWORDINLINE(0x700D, 0xABE9);
  366.  
  367. EXTERN_API_C( OSStatus )
  368. RegistryCStrEntryToPath            (const RegEntryID *        entryID,
  369.                                  RegCStrPathName *        pathName,
  370.                                  RegPathNameSize         pathSize)                            TWOWORDINLINE(0x700E, 0xABE9);
  371.  
  372. /*
  373.  * Parse a path name.
  374.  *
  375.  * Retrieve the last component of the path, and
  376.  * return a spec for the parent.
  377.  */
  378. EXTERN_API_C( OSStatus )
  379. RegistryCStrEntryToName            (const RegEntryID *        entryID,
  380.                                  RegEntryID *            parentEntry,
  381.                                  RegCStrEntryName *        nameComponent,
  382.                                  Boolean *                done)                                TWOWORDINLINE(0x700F, 0xABE9);
  383.  
  384. /* //////////////////////////////////////////////////////
  385. //
  386. // Property Management
  387. //
  388. ////////////////////////////////////////////////////// */
  389. /*-------------------------------
  390.  * Adding and removing properties
  391.  */
  392. EXTERN_API_C( OSStatus )
  393. RegistryPropertyCreate            (const RegEntryID *        entryID,
  394.                                  const RegPropertyName * propertyName,
  395.                                  const void *            propertyValue,
  396.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x7010, 0xABE9);
  397.  
  398. EXTERN_API_C( OSStatus )
  399. RegistryPropertyDelete            (const RegEntryID *        entryID,
  400.                                  const RegPropertyName * propertyName)                        TWOWORDINLINE(0x7011, 0xABE9);
  401.  
  402. EXTERN_API_C( OSStatus )
  403. RegistryPropertyRename            (const RegEntryID *        entry,
  404.                                  const RegPropertyName * oldName,
  405.                                  const RegPropertyName * newName)                            TWOWORDINLINE(0x7012, 0xABE9);
  406.  
  407. /*---------------------------
  408.  * Traversing the Properties of a name
  409.  *
  410.  */
  411. typedef struct OpaqueRegPropertyIter*     RegPropertyIter;
  412. EXTERN_API_C( OSStatus )
  413. RegistryPropertyIterateCreate    (const RegEntryID *        entry,
  414.                                  RegPropertyIter *        cookie)                                TWOWORDINLINE(0x7013, 0xABE9);
  415.  
  416. EXTERN_API_C( OSStatus )
  417. RegistryPropertyIterateDispose    (RegPropertyIter *        cookie)                                TWOWORDINLINE(0x7014, 0xABE9);
  418.  
  419. EXTERN_API_C( OSStatus )
  420. RegistryPropertyIterate            (RegPropertyIter *        cookie,
  421.                                  RegPropertyName *        foundProperty,
  422.                                  Boolean *                done)                                TWOWORDINLINE(0x7015, 0xABE9);
  423.  
  424. /*
  425.  * Get the value of the specified property for the specified entry.
  426.  *
  427.  */
  428. EXTERN_API_C( OSStatus )
  429. RegistryPropertyGetSize            (const RegEntryID *        entryID,
  430.                                  const RegPropertyName * propertyName,
  431.                                  RegPropertyValueSize *    propertySize)                        TWOWORDINLINE(0x7016, 0xABE9);
  432.  
  433. /*
  434.  * (*propertySize) is the maximum size of the value returned in the buffer
  435.  * pointed to by (propertyValue).  Upon return, (*propertySize) is the size of the
  436.  * value returned.
  437.  */
  438. EXTERN_API_C( OSStatus )
  439. RegistryPropertyGet                (const RegEntryID *        entryID,
  440.                                  const RegPropertyName * propertyName,
  441.                                  void *                    propertyValue,
  442.                                  RegPropertyValueSize *    propertySize)                        TWOWORDINLINE(0x7017, 0xABE9);
  443.  
  444. EXTERN_API_C( OSStatus )
  445. RegistryPropertySet                (const RegEntryID *        entryID,
  446.                                  const RegPropertyName * propertyName,
  447.                                  const void *            propertyValue,
  448.                                  RegPropertyValueSize     propertySize)                        TWOWORDINLINE(0x7018, 0xABE9);
  449.  
  450. /* //////////////////////////////////////////////////////
  451. //
  452. // Modifier Management
  453. //
  454. ////////////////////////////////////////////////////// */
  455. /*
  456.  * Modifiers describe special characteristics of names
  457.  * and properties.  Modifiers might be supported for
  458.  * some names and not others.
  459.  * 
  460.  * Device Drivers should not rely on functionality
  461.  * specified as a modifier.  These interfaces
  462.  * are for use in writing Experts.
  463.  */
  464. /*
  465.  * Get and Set operators for entry modifiers
  466.  */
  467. EXTERN_API_C( OSStatus )
  468. RegistryEntryGetMod                (const RegEntryID *        entry,
  469.                                  RegEntryModifiers *    modifiers)                            TWOWORDINLINE(0x7019, 0xABE9);
  470.  
  471. EXTERN_API_C( OSStatus )
  472. RegistryEntrySetMod                (const RegEntryID *        entry,
  473.                                  RegEntryModifiers         modifiers)                            TWOWORDINLINE(0x701A, 0xABE9);
  474.  
  475. /*
  476.  * Get and Set operators for property modifiers
  477.  */
  478. EXTERN_API_C( OSStatus )
  479. RegistryPropertyGetMod            (const RegEntryID *        entry,
  480.                                  const RegPropertyName * name,
  481.                                  RegPropertyModifiers *    modifiers)                            TWOWORDINLINE(0x701B, 0xABE9);
  482.  
  483. EXTERN_API_C( OSStatus )
  484. RegistryPropertySetMod            (const RegEntryID *        entry,
  485.                                  const RegPropertyName * name,
  486.                                  RegPropertyModifiers     modifiers)                            TWOWORDINLINE(0x701C, 0xABE9);
  487.  
  488. /*
  489.  * Iterator operator for entry modifier search
  490.  */
  491. EXTERN_API_C( OSStatus )
  492. RegistryEntryMod                (RegEntryIter *            cookie,
  493.                                  RegEntryIterationOp     relationship,
  494.                                  RegEntryID *            foundEntry,
  495.                                  Boolean *                done,
  496.                                  RegEntryModifiers         matchingModifiers)                    TWOWORDINLINE(0x701D, 0xABE9);
  497.  
  498. /*
  499.  * Iterator operator for entries with matching 
  500.  * property modifiers
  501.  */
  502. EXTERN_API_C( OSStatus )
  503. RegistryEntryPropertyMod        (RegEntryIter *            cookie,
  504.                                  RegEntryIterationOp     relationship,
  505.                                  RegEntryID *            foundEntry,
  506.                                  Boolean *                done,
  507.                                  RegPropertyModifiers     matchingModifiers)                    TWOWORDINLINE(0x701E, 0xABE9);
  508.  
  509.  
  510.  
  511. #if PRAGMA_STRUCT_ALIGN
  512.     #pragma options align=reset
  513. #elif PRAGMA_STRUCT_PACKPUSH
  514.     #pragma pack(pop)
  515. #elif PRAGMA_STRUCT_PACK
  516.     #pragma pack()
  517. #endif
  518.  
  519. #ifdef PRAGMA_IMPORT_OFF
  520. #pragma import off
  521. #elif PRAGMA_IMPORT
  522. #pragma import reset
  523. #endif
  524.  
  525. #ifdef __cplusplus
  526. }
  527. #endif
  528.  
  529. #endif /* __NAMEREGISTRY__ */
  530.  
  531.